AWS Step FunctionsをAWS CLIから使ってみる #reinvent

AWS re:Invent 2016 Keynoteで発表された、ビジュアライズなワークフローを使用して、分散アプリケーションと Microservicesのコンポーネントを簡単にコーディネート出来るサービス『Step Functions』をAWS CLIから使ってみます。

チュートリアル "Getting Started with AWS Step Functions" にある no-op な Pass ステートを利用したステートマシンを CLI から作成し、実行します。

Getting Started with AWS Step Functions - Developer Guide

AWS SDK For Python 向けは次の記事を参照下さい。

AWS Step FunctionsをAWS SDK For Pythonから使ってみる #reinvent

1.ステートマシンの作成

ステートマシンの定義

"Type" が "Pass" の no-op なステートマシンを作成します。

JSON ベースの Amazon States Language でステートマシンを定義します。

{
  "Comment": "A Hello World example of the Amazon States Language using an AWS Lambda Function",
  "StartAt": "HelloWorld",
  "States": {
    "HelloWorld": {
      "Type": "Pass",
      "Result": "Hello World!",
      "End": true
    }
  }
}

ステートマシンの実行用 IAM ロール

ステートマシンの実行用に自動生成された IAM Role を指定します。 IAM Role の ARN を控えておいて下さい。

自動生成されたロールは以下のとおりです。 Step Function が Lambda を呼び出せるようになっていますが、今回は Lambda 連携は行いません。

Permissions

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "lambda:InvokeFunction"
            ],
            "Resource": "*"
        }
    ]
}

Trust Relationships

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "states.eu-west-1.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

ステートマシンの作成

最後の CreateStateMachine API でステートマシンを作成します。

引数	意味
Name	ステートマシン名。リージョン毎にユニーク
Definition	ステートマシンのAmazon States Languageによる定義
RoleArn	ステートマシンが利用するIAMロールのARN

$ aws stepfunctions create-state-machine \
  --name foo \
  --definition file://definition.json \
  --role-arn "arn:aws:iam::123456789012:role/service-role/StatesExecutionRole-eu-west-1"
{
    "creationDate": 1481999304.311,
    "stateMachineArn": "arn:aws:states:eu-west-1:123456789012:stateMachine:foo"
}

作成したステートマシンを DescribeStateMachine API で確認しましょう。

describe 対象は ステートマシンの ARN を指定します。

$ aws stepfunctions describe-state-machine \
  --state-machine-arn arn:aws:states:eu-west-1:123456789012:stateMachine:foo
{
    "status": "ACTIVE",
    "definition": "{\n  \"Comment\": \"A Hello World example of the Amazon States Language using an AWS Lambda Function\",\n  \"StartAt\": \"HelloWorld\",\n  \"States\": {\n    \"HelloWorld\": {\n      \"Type\": \"Pass\",\n      \"Result\": \"Hello World!\",\n      \"End\": true\n    }\n  }\n}\n",
    "name": "foo",
    "roleArn": "arn:aws:iam::123456789012:role/service-role/StatesExecutionRole-eu-west-1",
    "stateMachineArn": "arn:aws:states:eu-west-1:123456789012:stateMachine:foo",
    "creationDate": 1481999304.311
}

ListSateMachines API を使うと、ステートマシン一覧を取得できます。

$ aws stepfunctions list-state-machines
{
    "stateMachines": [
        {
            "creationDate": 1481999304.311,
            "stateMachineArn": "arn:aws:states:eu-west-1:123456789012:stateMachine:foo",
            "name": "foo"
        }
    ]
}

2.ステートマシンの実行

作成したステートマシンを実行します。

実行用入力データを JSON で用意します。

{
    "Comment": "Insert your JSON here"
}

ステートマシンは StartExecution API で呼び出します。

$ aws stepfunctions start-execution \
  --state-machine-arn arn:aws:states:eu-west-1:123456789012:stateMachine:foo \
  --name `uuid` \
  --input file://input.json
{
    "startDate": 1481999666.169,
    "executionArn": "arn:aws:states:eu-west-1:123456789012:execution:foo:6f9657be-c487-11e6-b07e-97b68526373f"
}

引数	意味
StateMachineArn	ステートマシンのARN
Name	実行名。リージョン毎にユニーク。省略すると、サーバー側がユニークな名前を付与。
Input	ステートマシン実行用のインプット

実行結果を確認します。

$ aws stepfunctions describe-execution \
  --execution-arn arn:aws:states:eu-west-1:123456789012:execution:foo:6f9657be-c487-11e6-b07e-97b68526373f
{
    "status": "SUCCEEDED",
    "startDate": 1481999666.169,
    "name": "6f9657be-c487-11e6-b07e-97b68526373f",
    "executionArn": "arn:aws:states:eu-west-1:123456789012:execution:foo:6f9657be-c487-11e6-b07e-97b68526373f",
    "stateMachineArn": "arn:aws:states:eu-west-1:123456789012:stateMachine:foo",
    "stopDate": 1481999666.216,
    "output": "\"Hello World!\"",
    "input": "{\n    \"Comment\": \"Insert your JSON here\"\n}\n"
}

"status": "SUCCEEDED" と実行が成功したことがわかります。 "output": "\"Hello World!\"" と JSON で定義したとおりのアウトプットとなっています。

AMC の下図にあるようなステートの遷移は GetExecutionHistory API で取得します。

$ aws stepfunctions get-execution-history \
  --no-reverse-order \
  --execution-arn arn:aws:states:eu-west-1:123456789012:execution:foo:6f9657be-c487-11e6-b07e-97b68526373f
{
    "events": [
        {
            "timestamp": 1481999666.169,
            "executionStartedEventDetails": {
                "input": "{\n    \"Comment\": \"Insert your JSON here\"\n}\n",
                "roleArn": "arn:aws:iam::123456789012:role/service-role/StatesExecutionRole-eu-west-1"
            },
            "type": "ExecutionStarted",
            "id": 1,
            "previousEventId": 0
        },
        {
            "timestamp": 1481999666.216,
            "type": "PassStateEntered",
            "id": 2,
            "stateEnteredEventDetails": {
                "input": "{\n    \"Comment\": \"Insert your JSON here\"\n}\n",
                "name": "HelloWorld"
            },
            "previousEventId": 0
        },
        {
            "timestamp": 1481999666.216,
            "stateExitedEventDetails": {
                "output": "\"Hello World!\"",
                "name": "HelloWorld"
            },
            "type": "PassStateExited",
            "id": 3,
            "previousEventId": 2
        },
        {
            "executionSucceededEventDetails": {
                "output": "\"Hello World!\""
            },
            "timestamp": 1481999666.216,
            "type": "ExecutionSucceeded",
            "id": 4,
            "previousEventId": 3
        }
    ]
}

ListExecutions API を使うと、ステートマシンの実行一覧を取得できます。

$ aws stepfunctions list-executions \
  --state-machine-arn "arn:aws:states:eu-west-1:123456789012:stateMachine:foo"
{
    "executions": [
        {
            "status": "SUCCEEDED",
            "startDate": 1481999666.169,
            "name": "6f9657be-c487-11e6-b07e-97b68526373f",
            "executionArn": "arn:aws:states:eu-west-1:123456789012:execution:foo:6f9657be-c487-11e6-b07e-97b68526373f",
            "stateMachineArn": "arn:aws:states:eu-west-1:123456789012:stateMachine:foo",
            "stopDate": 1481999666.216
        }
    ]
}

3. ステートマシンの削除

最後に作成したステートマシンを DeleteStateMachine API で削除します。

$ aws stepfunctions delete-state-machine \
  --state-machine-arn "arn:aws:states:eu-west-1:123456789012:stateMachine:foo"

削除したステートマシンを describe すると "status" : "DELETING" となっています。

$ aws stepfunctions describe-state-machine \
  --state-machine-arn arn:aws:states:eu-west-1:123456789012:stateMachine:foo
{
    "status": "DELETING",
    ...
    snip
    ...
}

しばらく待つと、ステートマシンの削除が完了します。

削除完了後に DescribeStateMachine API を実行すると、次のように StateMachineDoesNotExist エラーが発生します。

$ aws stepfunctions describe-state-machine \
  --state-machine-arn arn:aws:states:eu-west-1:123456789012:stateMachine:foo
An error occurred (StateMachineDoesNotExist) when calling the DescribeStateMachine operation: State Machine Does Not Exist: 'arn:aws:states:eu-west-1:123456789012:stateMachine:foo'

まとめ

AWS Step Functions を AWS CLI から使う方法を紹介しました。 cron などで定期的にシェルから実行するケースでは有効ではないかと思います。

API を呼び出すだけなら CLI でも OK ですが、グラフ化された状態を確認したければ、素直に管理コンソールから確認すべきでしょう。

参考リンク

• https://aws.amazon.com/step-functions/
• http://docs.aws.amazon.com/step-functions/latest/dg/hello.html
• http://docs.aws.amazon.com/cli/latest/reference/stepfunctions/index.html